% render "layouts/guides.html" do

Origen encourages an agile approach to documentation and pattern generation is
no exception.
Tools are provided to create test patterns that are self-documenting and by taking
a little care you can produce very detailed (and of course 100% accurate) documentation
of your test patterns for free.

The pattern generation command has the following switches:

~~~text
origen g bistcom           # Generate a regular pattern
origen g bistcom --doc     # Output documentation of that pattern to the terminal
origen g bistcom --html    # Generate pre-formatted HTML documentation for inclusion in a web page
~~~

The following methods are available to control the documentation output from the pattern
generator...

#### Debug Documentation

Comments that may help with debug of patterns on the tester can be injected into
the pattern via the <code>cc</code> method, as with all methods related to
pattern documentation this is globally available.

~~~ruby
cc "Entering test mode now"
test.mode.write!(RAMBIST_MODE)
reset!
~~~

The method argument is a regular string and dynamic segments can be embedded and
formatted using any regular Ruby.

~~~ruby
delay_cycles = 100
cc "Wait for #{delay_cycles} cycles for the mode to latch"

address = 0x12
cc "Set the target address to: 0x%04X" % address
~~~

This will produce pattern output that looks like this:

~~~text
// Wait for 100 cycles for the mode to latch
// Set the target address to 0x0012
~~~

<code>c1</code> is an alias for <code>cc</code>.

These low level comments will appear in the pattern but they will not be included
when a document of the pattern is generated.

A <code>c2</code> method is available to elevate the importance of a subset of
these low level comments
such that they will be included in generated documentation.

~~~ruby
cc "You won't see me in the docs"
c1 "Or me"
c2 "But you will see me!"
~~~

#### Documenting Major Steps

Major steps in the pattern can be highlighted using the <code>ss</code> method.

~~~ruby
ss "Enter RAM BIST mode"

# A block form is also available
ss do
  vdd_core = 1.7
  cc "Enter RAM BIST mode with the following options:"
  cc "  Vdd core - #{vdd_core}v"
end
~~~

This will produce the following output in the pattern:

~~~text
// #######################################################################
// # Enter RAM BIST mode
// #######################################################################

// #######################################################################
// # Enter RAM BIST mode with the following options:
// #   Vdd core - 1.7v
// #######################################################################
~~~

Any comments defined in this way are considered more important than the regular
<code>cc</code> comments and they will be automatically included in the
generated documentation.

#### Documenting Structure

When presenting documentation it is useful to know something about the structure
of the pattern, this allows vectors to be grouped into sections like 'startup', 
'shutdown', etc.

Such structure can be described using the <code>pp</code> method:

~~~ruby
pp "Startup" do
  $dut.enter_ram_bist_mode
  $dut.ram.configure_for_test
end

def enter_ram_bist_mode
  pp "Enter RAM BIST mode" do
    # Mode entry code here...
  end
end  
~~~

This would produce comments in the pattern that look like this:

~~~text
// #######################################################################
// # Startup
// #######################################################################

// #######################################################################
// # Enter RAM BIST mode
// #######################################################################
~~~

However this difference vs. the <code>ss</code> method is that information about
the structure has been provided - it can be determined that the enter RAM bist
section is a sub-section of the wider startup sequence.

This comes into play when the pattern documentation is generated as HTML,
now we will see something like this (click to expand):

<div class="panel-group">
<div class="panel panel-default">
<div class="panel-heading clickable" data-toggle="collapse" data-parent="#panel2" href="#collapseComment1">
<a class="no-underline">
Startup
</a>
</div>
<div id="collapseComment1" class="panel-collapse collapse">
<div class="panel-body" markdown="1">

<div class="panel panel-default">
<div class="panel-heading clickable" data-toggle="collapse" data-parent="#panel2" href="#collapseComment2">
  <a class="no-underline">
  Enter RAM BIST mode
  </a>
</div>
<div id="collapseComment2" class="panel-collapse collapse">
<div class="panel-body" markdown="1">

~~~text
# Some comments generated by the RAM BIST entry sequence
~~~

</div>
</div>
</div>
</div>
</div>
</div>
</div>

#### Adding Annotations

Sometimes it will be helpful to add some annotations to describe what sections
of the pattern are doing, this can be done via the <code>annotate</code>
method.

Any annotations will not be output in the actual pattern but will be included
in generated documentation.

Here is the above example with some annotations added:

~~~ruby
pp "Startup" do
  annotate "Perform startup operations that are common to all patterns."
  $dut.enter_ram_bist_mode
  $dut.ram.configure_for_test
end

def enter_ram_bist_mode
  pp "Enter RAM BIST mode" do

    annotate <<-END
      This is an example of a multi-line annotation. Anything you write here
      will be parsed as markdown, so you can do things like:

      * Create bullet
      * Lists

      ~~~ruby
      # Embed some code examples
      $dut.enter_ram_bist_mode
      ~~~

      Or create [links](http://origen.freescale.net)
    END

    # Mode entry code here...
  end
end  
~~~

This would produce the following snippet of documentation:



<div class="panel-group">
<div class="panel panel-default">
<div class="panel-heading clickable" data-toggle="collapse" data-parent="#panel2" href="#collapseComment3">
<a class="no-underline">
Startup
</a>
</div>
<div id="collapseComment3" class="panel-collapse collapse">
<div class="panel-body" markdown="1">

Perform startup operations that are common to all patterns.

<div class="panel panel-default">
<div class="panel-heading clickable" data-toggle="collapse" data-parent="#panel2" href="#collapseComment4">
<a class="no-underline">
Enter RAM BIST mode
</a>
</div>
<div id="collapseComment4" class="panel-collapse collapse">
<div class="panel-body" markdown="1">

This is an example of a multi-line annotation. Anything you write here
will be parsed as markdown, so you can do things like:

* Create bullet
* Lists

~~~ruby
# Embed some code examples
$dut.enter_ram_bist_mode
~~~

Or create [links](http://origen.freescale.net)

~~~text
# Some comments generated by the RAM BIST entry sequence
~~~

</div>
</div>
</div>
</div>
</div>
</div>
</div>


#### Summarizing Long Sections

Sometimes it is not necessary to list out every comment or operation when documenting 
a pattern. For example if the pattern downloads some functional code to be executing
on the chip it is not really necessary to include the entire code download in the
pattern document.

For these scenarios a <code>snip</code> method is available which will output the
given number of documentation lines and then enter a message to indicate that
the remainder of the output has been snipped for efficiency.

Here is an example of how to use it, here the comments generated by the contained
section will be limited to 10 lines:

~~~ruby
  snip 10 do
    # Download some verbose LRE code here
  end
~~~

#### Pattern Headers

When you generate a pattern, you'll notice the top section contains some useful information, such as the user that generated the pattern, a
timestamp, the current environment, version of the application, the gems used, etc.  This section is called the <code>pattern header</code> and may look something
like this:

~~~
// ***************************************************************************
// GENERATED:
//   Time:    24-Jun-2018 10:06AM
//   By:      coreyeng
//   Mode:    debug
//   Command: origen g iterator_postfix_test_x_bx -t debug.rb
// ***************************************************************************
// ENVIRONMENT:
//   Application
//     Source:    git@github.com:Origen-SDK/origen.git
//     Version:   0.33.1
//     Branch:    fixes(c4e8e1d0db0) (+local edits)
//   Origen
//     Source:    https://github.com/Origen-SDK/origen
//     Version:   0.33.1
//   Plugins
//     atp:                      1.1.0
//     origen_core_support:      0.2.3
//     origen_debuggers:         0.6.0
//     origen_doc_helpers:       0.5.2
//     origen_testers:           0.16.1
//     origen_updater:           0.7.0
// ***************************************************************************
~~~

The pattern header can also serve as place for the application, current plugin, or other shared plugins, to add specific comments that relate to
how that pattern was generated or how it should be used.

Three [configuration attributes](<%= path "guides/plugins/app/" %>)
exist that will inject additional comments into the pattern header: <code>shared_pattern_header</code>, <code>application_pattern_header</code>,
and <code>current_plugin_pattern_header</code>.

These configuration attributes should be <code>blocks</code> that accept an <code>options hash</code> and return either a <code>String</code>,
<code>Array of Strings</code>, or another <code>block</code>. <code>Strings</code> and <code>Arrays</code> will have the formatting handled
for you, but <code>blocks</code> can handle the formatting themselves and can provide custom header comment formatting.

Assume we have two plugins, <code>plugin1</code> and <code>plugin2</code> that are each needed to generate a pattern located in the
application <code>my_app</code>. With <u>no plugin set</u> and with the configuration attributes set as follows:

~~~ruby
# plugin1/config/application.rb

config.shared_pattern_header do
  "Hi from shared #{Origen.app!.name}!"
end

config.current_plugin_pattern_header do
  "Hi from current plugin: #{Origen.app!.name}!"
end

# plugin2/config/application.rb

config.shared_pattern_header do
  "Hi from shared #{Origen.app!.name}!"
end

config.current_plugin_pattern_header do
  "Hi from current plugin: #{Origen.app!.name}!"
end

# my_app/config/application.rb

config.shared_pattern_header do
  "Hi from application #{Origen.app!.name}!"
end
~~~

generating a pattern, will yield the following appended to the pattern header:

~~~
// ***************************************************************************
// Header Comments From Shared Plugins:
//   Header Comments From Shared Plugin: plugin1:
//     Hi from shared plugin1!
//   Header Comments From Shared Plugin: plugin2:
//     Hi from shared plugin2!
// ***************************************************************************
// Header Comments From Application: my_app:
//   Hi from application my_app!
// ***************************************************************************
~~~

You'll notice here that there's no <code>current_plugin_pattern_header</code> printed. This will be printed when
the current plugin is set to a plugin that has this configuration attribute. Setting the current plugin to
<code>plugin1</code>, you'll now get both shared headers, the current plugin's header, and the application header:

~~~
// ***************************************************************************
// Header Comments From Shared Plugins:
//   Header Comments From Shared Plugin: plugin1:
//     Hi from shared plugin1!
//   Header Comments From Shared Plugin: plugin2:
//     Hi from shared plugin2!
// ***************************************************************************
// Header Comments From The Current Plugin: plugin1:
//   Hi from current plugin plugin1!
// ***************************************************************************
// Header Comments From Application: my_app:
//   Hi from application my_app!
// ***************************************************************************
~~~

As previously said, you can provide either a <code>block, proc, or lambda</code> (anything that responds to <code>call</code> will work) and use 
<code>cc, ss, c2</code>, etc. to handle arbitrary headers or formatting. For example, changing <code>shared_pattern_header</code> in <code>plugin2</code>:

~~~ruby
# plugin2/config/application.rb

config.shared_pattern_header do
  proc do 
    c2 "Hi from block in #{Origen.app!.name}"
  end
end
~~~

Will show the following in the pattern header:

~~~
// ***************************************************************************
// Header Comments From Shared Plugins:
//   Header Comments From Shared Plugin: plugin1:
//     Hi from shared plugin1!
//   Header Comments From Shared Plugin: plugin2:
// Hi from block in plugin2!
// ***************************************************************************
// Header Comments From The Current Plugin: plugin1:
//   Hi from current plugin plugin1!
// ***************************************************************************
// Header Comments From Application: my_app:
//   Hi from application my_app!
// ***************************************************************************
~~~

<div class ="alert alert-info" role="alert">
  <strong>Info:</strong> Although the guides here show an <code>option hash</code>, there are currently no options <i>actually</i> being passed in, i.e., its just
  an empty hash. This is only because this is a new feature, and by using an options hash here, future versions of Origen will be able to add any options that should
  go to the pattern header without affecting the method prototype.
</div>

<div class="alert alert-warning" role="alert">
  <strong>Deprecated:</strong> You may see <code>config.pattern_header</code> in some legacy applications. <code>config.pattern_header</code> is limited to only the
  current plugin and must handle formatting itself. This is now deprecated but is left in for legacy purposes.
</div>

% end
